Background

The initial goal used to be to better describe our events - which bubble and which can be prevented as part of the API reference docs. While this is the benefit for the end-users, there is another enhancement for component developers, explained below.

Change

The @event decorator is enhanced to provide two new fields describing components' events - cancelable and bubbles, previously configurable via the UI5Element.fireEvent only, allowing more declarative way to configure these event settings:

• cancelable - if set to true the event can be prevented with preventDefualt() (by default is false)
• bubbles - if set to false the event will NOT bubble up the DOM tree (by default is true)

Usage

• Both cancelable and bubbles are false as not configured (false by default):

@event("my-event")

• Both cancelable and bubbles are true as configured:

@event("my-event", {
	cancelable: true,
	bubbles: true,
})

The fireDecoratorEvent Method

The fireDecoratorEvent method considers the the event decorator.

• Fires the event with cancelable: false, bubbles: false as they are not configured in the @event

@event("my-event")

this.fireDecoratorEvent("my-event")

• Fires the event with cancelable: true, bubbles: false, configured in the @event

@event("my-event", {
	cancelable: true,
	bubbles: true,
})

this.fireDecoratorEvent("my-event")

Unlike fireEvent, the fireDecoratorEvent method has only two parameters - the event name and the event detail as the rest of the settings are configurable via the event decorator.

The fireEvent Method

The fireEvent Method does not consider the event decorator and works as before.

• Fires an event with cancelable: false, bubbles: true as default

this.fireEvent("my-event", { escPressed });

• Fires an event cancelable: true, bubbles: false, passed as params

this.fireEvent("my-event", { escPressed }, true, false);

API Reference

As mentioned we start showing this information in our website as follows. This comes out of the box, nothing for component developers to take care.

Fixes: #9909